Fix the follow-ups from the #87–#89 review (#91–#96) - #97

Fixes the follow-ups found while reviewing #87–#89.

Fixes #91, fixes #92, fixes #93, fixes #94, fixes #95, fixes #96

Changes

• IOException/ParseException raised from a PHP warning lose the warning text — message is the error number #91: exceptions now keep the PHP warning text. ParseException::initializeFromError() passed its arguments in the wrong order, so the message was the error number and the code was 0. It now throws new static($errstr, $errno, ...), and the identical override in IOException has been removed. This changes the exception message, so the CHANGELOG notes it for anyone matching on the old text.
• writeHTML() throws ParseException instead of IOException when the file cannot be written #92: writeHTML() throws IOException when the file can't be written, like the other write*() methods. testFailWriteHTML() now calls writeHTML(); it used to call writeXML().
• Consolidate the seven set_error_handler/restore_error_handler blocks into one finally-based helper #95: one error-handler helper. The seven set_error_handler / catch / restore_error_handler blocks in DOM and DOMQuery now all go through DOM::withErrorHandler(), which restores the handler in finally. Before, any throwable that wasn't a QueryPath\Exception (a TypeError, or an exception from a stream wrapper) left QueryPath's handler installed.
• tag() warns and returns NULL when the first match is not an element #93: tag() returns '' when the first match isn't an element, for example a text node from contents(). That matches what it already returns for an empty set.
• QPXML::createElement() only resolves prefixes declared on the document element #94: QPXML::createElement() resolves the prefix against the first matched element, not the document, so a prefix declared below the root now works. The foreach that only ever ran once is replaced with get(0).
• Share one implementation between the QPXML::cdata(), comment() and pi() getters #96: cdata(), comment() and pi() share one private helper, firstChildText(). pi() now has a full docblock. There is no behaviour change, so this one has no CHANGELOG entry.

Tests

Each fix has a test that fails on main and passes on this branch:

• IOException/ParseException raised from a PHP warning lose the warning text — message is the error number #91: the exception message contains the warning text, and the code is E_WARNING.
• writeHTML() throws ParseException instead of IOException when the file cannot be written #92: writeHTML() to an unwritable path throws IOException.
• Consolidate the seven set_error_handler/restore_error_handler blocks into one finally-based helper #95: testErrorHandlerRestoredAfterForeignThrowable uses a new ThrowingStreamWrapper fixture to raise a RuntimeException inside writeXML(), writeHTML(), writeHTML5() and a load with a stream context. It then checks that the previous error handler is back. parseXMLString() and prepareInsert() have no such test, because there's no reliable way to make them throw a non-QueryPath exception.
• tag() warns and returns NULL when the first match is not an element #93: tag() on a match set whose first node is a text, comment, processing-instruction or element node.
• QPXML::createElement() only resolves prefixes declared on the document element #94: prefixes declared below the root, on the root, and out of scope; only the first match is used; an empty match set.
• Share one implementation between the QPXML::cdata(), comment() and pi() getters #96: before the refactor, I added tests for the cases with nothing to find and for the first hit across several matches, and ran them green on the old code.

The full suite (415 tests), composer run lint and composer run lint:min-php pass locally on PHP 8.5. CI covers 7.1–8.4.

Not in this PR

Other methods still call element-only DOM methods on a match without checking its type, so they can fail on a contents() result the way tag() did: the attr() getter and setter, addClass(), removeClass(), css(), hasClass(), hasAttr() and removeAttr(). That's the same class of bug as #93, but wider in scope, and probably best fixed with one element-only accessor on DOM. Tracked in #98.

🤖 Generated with Claude Code